/*
 * Background Flickr: Copyright (C) 2009  Craig McNicholas
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 * 
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

package com.ddw.app.bflickr.flickr.api;

import com.ddw.app.bflickr.flickr.api.request.FlickrApiOnRequestCompletedEventArgs;


/**
 * Interface for request objects. The object should be able to handle 
 * asynchronous requests and be able to provide callbacks to listeners.
 * @author craig
 *
 */
public interface FlickrRequest {

	/**
	 * Starts the asynchronous request
	 */
	public void start();
	
	/**
	 * Adds a listener to the request object. Asynchronous responses can be 
	 * in the form of completion or errors.
	 * @param listener the listener to attach to the request
	 */
	public void addListener(FlickrRequestListener listener);
	
	/**
	 * Removes a listener from the request object.
	 * @param listener the listener to remove
	 */
	public void removeListener(FlickrRequestListener listener);
	
	/**
	 * Clears all listeners attached to the request
	 */
	public void clearListeners();
	
	/**
	 * Setter for the url property. This is the url which the request object 
	 * will attempt to retrieve a response from.
	 * @param url the url to request
	 */
	public void setUrl(FlickrURL url);
	
	/**
	 * Getter for the url property. This is the url which the request object 
	 * will attempt to retrieve a response from.
	 * @return the url to request
	 */
	public FlickrURL getUrl();
	
	/**
	 * Triggers the error handlers for all listeners
	 * @param ex the throwable to pass to the listeners
	 */
	public void raiseOnRequestErrorEvent(Throwable throwable);
	
	/**
	 * Triggers the completed handlers for all listeners
	 * @param data the data to pass to the listeners
	 */
	public void raiseOnCompleted(FlickrApiOnRequestCompletedEventArgs data);
	
	/**
	 * Triggers the parse error handlers for all listeners
	 * @param ex the throwable to pass to the listeners
	 */
	public void raiseOnParseError(Throwable throwable);
	
}
